Glyphs
******

A glyph is an object that is used for pixmaps and non-textual strings that are displayed in the text of a buffer, in the margins, or in the toolbar.  The actual image that is displayed (as opposed to its position or clipping) is defined by an image specifier object contained within the glyph.

 -- Function: glyphp object
     This function returns t if OBJECT is a glyph.

Glyph Functions
===============

Creating Glyphs
---------------

 -- Function: make-glyph &optional spec-list
     This function creates a new glyph object, with the given specification list used to initialize the glyph's image specifier. SPEC-LIST can be a list of specifications (each of which is a cons of a locale and a list of inst-pairs, each of which is a cons of a tag and an instantiator), a single instantiator, a list of instantiators, or almost any other reasonable form (specifically anything accepted by canonicalize-spec-list).  See Specifiers for more information about specifiers.

 -- Function: make-glyph-internal
     This function creates a new, uninitialzed glyph.

Glyph Properties
----------------

The following symbols have predefined meanings:

image
     The image used to display the glyph.

baseline
     Percent above baseline that glyph is to be displayed.

contrib-p
     Whether the glyph contributes to the height of the line it's on.

face
     Face of this glyph (not a specifier).

 -- Function: set-glyph-property glyph property value &optional locale tag-set how-to-add
     This function changes a property of a GLYPH.

     For built-in properties, the actual value of the property is a specifier and you cannot change this; but you can change the specifications within the specifier, and that is what this function will do.  For user-defined properties, you can use this function to either change the actual value of the property or, if this value is a specifier, change the specifications within it.

     If PROPERTY is a built-in property, the specifications to be added to this property can be supplied in many different ways:

          If VALUE is a simple instantiator (e.g. a string naming a pixmap filename) or a list of instantiators, then the instantiator(s) will be added as a specification of the property for the given LOCALE (which defaults to global if omitted).

          If VALUE is a list of specifications (each of which is a cons of a locale and a list of instantiators), then LOCALE must be nil (it does not make sense to explicitly specify a locale in this case), and specifications will be added as given.

          If VALUE is a specifier (as would be returned by glyph-property if no LOCALE argument is given), then some or all of the specifications in the specifier will be added to the property.  In this case, the function is really equivalent to copy-specifier and LOCALE has the same semantics (if it is a particular locale, the specification for the locale will be copied; if a locale type, specifications for all locales of that type will be copied; if nil or all, then all specifications will be copied).

     HOW-TO-ADD should be either nil or one of the symbols prepend, append, remove-tag-set-prepend, remove-tag-set-append, remove-locale, remove-locale-type, or remove-all.  See copy-specifier and add-spec-to-specifier for a description of what each of these means.  Most of the time, you do not need to worry about this argument; the default behavior usually is fine.

     In general, it is OK to pass an instance object (e.g. as returned by glyph-property-instance) as an instantiator in place of an actual instantiator.  In such a case, the instantiator used to create that instance object will be used (for example, if you set a font-instance object as the value of the font property, then the font name used to create that object will be used instead).  If some cases, however, doing this conversion does not make sense, and this will be noted in the documentation for particular types of instance objects.

     If PROPERTY is not a built-in property, then this function will simply set its value if LOCALE is nil.  However, if LOCALE is given, then this function will attempt to add VALUE as the instantiator for the given LOCALE, using add-spec-to-specifier.  If the value of the property is not a specifier, it will automatically be converted into a generic specifier.

 -- Function: glyph-property glyph property &optional locale
     This function returns GLYPH's value of the given PROPERTY.

     If LOCALE is omitted, the GLYPH's actual value for PROPERTY will be returned.  For built-in properties, this will be a specifier object of a type appropriate to the property (e.g. a font or color specifier).  For other properties, this could be anything.

     If LOCALE is supplied, then instead of returning the actual value, the specification(s) for the given locale or locale type will be returned.  This will only work if the actual value of PROPERTY is a specifier (this will always be the case for built-in properties, but not or not may apply to user-defined properties).  If the actual value of PROPERTY is not a specifier, this value will simply be returned regardless of LOCALE.

     The return value will be a list of instantiators (e.g. vectors specifying pixmap data), or a list of specifications, each of which is a cons of a locale and a list of instantiators.  Specifically, if LOCALE is a particular locale (a buffer, window, frame, device, or global), a list of instantiators for that locale will be returned.  Otherwise, if LOCALE is a locale type (one of the symbols buffer, window, frame, or device), the specifications for all locales of that type will be returned. Finally, if LOCALE is all, the specifications for all locales of all types will be returned.

     The specifications in a specifier determine what the value of PROPERTY will be in a particular domain or set of circumstances, which is typically a particular Emacs window along with the buffer it contains and the frame and device it lies within.  The value is derived from the instantiator associated with the most specific locale (in the order buffer, window, frame, device, and global) that matches the domain in question.  In other words, given a domain (i.e. an Emacs window, usually), the specifier for PROPERTY will first be searched for a specification whose locale is the buffer contained within that window; then for a specification whose locale is the window itself; then for a specification whose locale is the frame that the window is contained within; etc.  The first instantiator that is valid for the domain (usually this means that the instantiator is recognized by the device [i.e. the X server or TTY device] that the domain is on).  The function glyph-property-instance actually does all this, and is used to determine how to display the glyph.

 -- Function: glyph-property-instance glyph property &optional domain default no-fallback
     This function returns the instance of GLYPH's PROPERTY in the specified DOMAIN.

     Under most circumstances, DOMAIN will be a particular window, and the returned instance describes how the specified property actually is displayed for that window and the particular buffer in it.  Note that this may not be the same as how the property appears when the buffer is displayed in a different window or frame, or how the property appears in the same window if you switch to another buffer in that window; and in those cases, the returned instance would be different.

     The returned instance will typically be an image-instance object or a string (this is slated to change in 19.13), and you can query it using the appropriate object-specific functions.  For example, you could use image-instance-depth to find out the depth (number of color planes) of a pixmap displayed in a particular window.  The results might be different from the results you would get for another window (perhaps the user specified a different image for the frame that window is on; or perhaps the same image was specified but the window is on a different X server, and that X server has different color capabilities from this one).

     DOMAIN defaults to the selected window if omitted.

     DOMAIN can be a frame or device, instead of a window.  The value returned for a such a domain is used in special circumstances when a more specific domain does not apply; for example, a frame value might be used for coloring a toolbar, which is conceptually attached to a frame rather than a particular window.  The value is also useful in determining what the value would be for a particular window within the frame or device, if it is not overridden by a more specific specification.

     If PROPERTY does not name a built-in property, its value will simply be returned unless it is a specifier object, in which case it will be instanced using specifier-instance.

     Optional arguments DEFAULT and NO-FALLBACK are the same as in specifier-instance.  See Specifiers.

Glyph Convenience Functions
---------------------------

 -- Function: glyph-image glyph &optional locale

 -- Function: set-glyph-image glyph spec &optional locale tag-set how-to-add

 -- Function: glyph-image-instance glyph &optional domain default no-fallback

 -- Function: glyph-contrib-p glyph &optional locale
     This function returns whether GLYPH contributes to its line height.  GLYPH and LOCALE are as in glyph-property.

 -- Function: set-glyph-contrib-p glyph spec &optional locale tag-set how-to-add

 -- Function: glyph-contrib-p-instance glyph &optional domain default no-fallback

 -- Function: glyph-baseline glyph &optional locale

 -- Function: set-glyph-baseline glyph spec &optional locale tag-set how-to-add

 -- Function: glyph-baseline-instance glyph &optional domain default no-fallback

Images
======

Image Specifiers
----------------

An image specifier is used for images (pixmaps and the like).  It is used to describe the actual image in a glyph.  It is instanced as an image-instance.

An image instantiator should be a string or a vector of the form

      [TYPE :KEYWORD VALUE ...]

i.e. a type symbol followed by zero or more alternating keyword-value pairs.  TYPE should be one of

nothing
     (Don't display anything; no keywords are valid for this.)

string
     (Display this image as a text string.)

formatted-string
     (Display this image as a text string, with replaceable fields; #### not implemented in 19.13.)

xbm
     (An X bitmap; only if X support was compiled into this XEmacs.)

xpm
     (An XPM pixmap; only if XPM support was compiled into this XEmacs.)

xface
     (An X-Face bitmap, used to encode people's faces in e-mail messages; only if X-Face support was compiled into this XEmacs.)

autodetect
     (XEmacs tries to guess what format the data is in.  If X support exists, the data string will be checked to see if it names a filename. If so, and this filename contains XBM or XPM data, the appropriate sort of pixmap will be created.  Otherwise, the image will be displayed as a string.  If no X support exists, the image will always be displayed as a string.)

The valid keywords are:

:data
     (Inline data.  For most formats above, this should be a string.  For XBM images, this should be a cons of three elements: width, height, and a string of bit data.)

:file
     (Data is contained in a file.  The value is the name of this file.  If both :data and :file are specified, the image is created from what is specified in :data and the string in :file becomes the value of the image-instance-file-name function when applied to the resulting image-instance.)

:mask-data
     (Only for XBM images.  This specifies a mask to be used with the bitmap.  The format is a cons of width, height, and bits, like for :data.)

:mask-file
     (Only for XBM images.  This specifies a file containing the mask data.)

:color-symbols
     (Only for XPM images.  This specifies an alist that maps strings that specify symbolic color names to the actual color to be used for that symbolic color (in the form of a string or a color-specifier object). If this is not specified, the contents of xpm-color-symbols are used to generate the alist.)

If instead of a vector, the instantiator is a string, it will be looked up according to the specs in the device-type-image-conversion-list for the device type of the domain over which the image is being instantiated.

If the instantiator is a string, it will be read in at the time that the instantiator is added to the image, and the instantiator will be converted into one of the [FILENAME ...] forms.  This implies that the file must exist when the instantiator is added to the image, but does not need to exist at any other time (e.g. it may be a temporary file).

 -- Function: image-specifier-p object
     This function returns non-nil if OBJECT is an image specifier.

 -- Variable: xpm-color-symbols
     This variable holds definitions of logical color-names used when reading XPM files.  Elements of this list should be of the form (COLOR-NAME FORM-TO-EVALUATE).  The COLOR-NAME should be a string, which is the name of the color to define; the FORM-TO-EVALUATE should evaluate to a color specifier object, or a string to be passed to make-color-instance (see Colors).  If a loaded XPM file references a symbolic color called COLOR-NAME, it will display as the computed color instead.

     The default value of this variable defines the logical color names "foreground" and "background" to be the colors of the default face.

 -- Variable: x-bitmap-file-path
     A list of the directories in which X bitmap files may be found.  If nil, this is initialized from the "*bitmapFilePath" resource.  This is used by the make-image-instance function (however, note that if the environment variable XBMLANGPATH is set, it is consulted first).

Image Instantiator Conversion
-----------------------------

 -- Function: set-device-type-image-conversion-list device-type list
     This function sets the image-conversion-list for devices of the given DEVICE-TYPE.  The image-conversion-list specifies how image instantiators that are strings should be interpreted.  Each element of the list should be a list of two elements (a regular expression string and a vector) or a list of three elements (the preceding two plus an integer index into the vector).  The string is converted to the vector associated with the first matching regular expression.  If a vector index is specified, the string itself is substituted into that position in the vector.

     Note: The conversion above is applied when the image instantiator is added to an image specifier, not when the specifier is actually instantiated.  Therefore, changing the image-conversion-list only affects newly-added instantiators.  Existing instantiators in glyphs and image specifiers will not be affected.

 -- Function: device-type-image-conversion-list device-type
     This function returns the image-conversion-list for devices of the given DEVICE-TYPE.

Image Instances
---------------

Image-instance objects encapsulate the way a particular image (pixmap, etc.) is displayed on a particular device.  In most circumstances, you do not need to directly create image instances; use a glyph or an image- specifier instead. (Most functions and data structures that want an image are designed to take either a glyph or an image-specifier.)

 -- Function: image-instance-p object
     This function returns non-nil if OBJECT is an image instance.

 -- Function: make-image-instance data &optional device force-mono noerror
     This function creates a new image-instance object.

 -- Function: colorize-image-instance image-instance foreground background
     This function makes the image instance be displayed in the given colors.  Image instances come in two varieties: bitmaps, which are 1 bit deep which are rendered in the prevailing foreground and background colors; and pixmaps, which are of arbitrary depth (including 1) and which have the colors explicitly specified.  This function converts a bitmap to a pixmap.  If the image instance was a pixmap already, nothing is done (and nil is returned).  Otherwise t is returned.

 -- Function: image-instance-depth image-instance
     This function returns the depth of the image instance. This is 0 for a bitmap, or a positive integer for a pixmap.

 -- Function: image-instance-file-name image-instance
     This function returns the file name from which the given image instance was read, or nil if the image instance was created from Lisp data (the lisp data is not retained, since it usually won't be needed again and might be quite large).

 -- Function: image-instance-height image-instance
     This function returns the height of the image instance, in pixels.

 -- Function: image-instance-width image-instance
     This function returns the width of the image instance, in pixels.

 -- Function: set-image-instance-hotspot image-instance x y
     This function sets the image instance's hotspot.  This is a point relative to the origin of the pixmap.  When a pixmap is used as a cursor or similar pointing indicator, the hotspot is the point on the pixmap that sits over the location that the pointer points to.  This is, for example, the tip of the arrow or the center of the crosshairs.

 -- Function: image-instance-hotspot-x image-instance
     This function returns the X coordinate of the image instance's hotspot.

 -- Function: image-instance-hotspot-y image-instance
     This function returns the Y coordinate of the image instance's hotspot.

Cursors
=======

Cursors are scheduled to be overhauled in 19.13. Watch this space for more info.